001    /**
002     * Copyright 2003-2004 The Apache Software Foundation
003     * Copyright 2005 Stephen McConnell
004     *
005     * Licensed under the Apache License, Version 2.0 (the "License");
006     * you may not use this file except in compliance with the License.
007     * You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package net.dpml.cli;
018    
019    import java.util.ListIterator;
020    
021    /**
022     * An Option that can process values passed on the command line in the form
023     * "--file README".
024     *
025     * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
026     * @version 1.0.0
027     */
028    public interface Argument extends Option
029    {
030       /**
031        * Returns the initial separator character or
032        * '\0' if no character has been set.
033        * 
034        * @return char the initial separator character
035        */
036        char getInitialSeparator();
037        
038       /**
039        * Processes the "README" style element of the argument.
040        *
041        * Values identified should be added to the CommandLine object in
042        * association with this Argument.
043        *
044        * @see WriteableCommandLine#addValue(Option,Object)
045        *
046        * @param commandLine The CommandLine object to store results in.
047        * @param args The arguments to process.
048        * @param option The option to register value against.
049        * @throws OptionException if any problems occur.
050        */
051        void processValues( 
052          WriteableCommandLine commandLine, ListIterator args, Option option )
053          throws OptionException;
054        
055        /**
056         * Adds defaults to a CommandLine.
057         * 
058         * @param commandLine the CommandLine object to store defaults in.
059         * @param option the Option to store the defaults against.
060         */
061        void defaultValues( WriteableCommandLine commandLine, Option option );
062    
063        /**
064         * Performs any necessary validation on the values added to the
065         * CommandLine.
066         *
067         * Validation will typically involve using the
068         * CommandLine.getValues(option) method to retrieve the values
069         * and then either checking each value.  Optionally the String
070         * value can be replaced by another Object such as a Number
071         * instance or a File instance.
072         *
073         * @see CommandLine#getValues(Option)
074         *
075         * @param commandLine The CommandLine object to query.
076         * @param option The option to lookup values with.
077         * @throws OptionException if any problems occur.
078         */
079        void validate( WriteableCommandLine commandLine, Option option )
080            throws OptionException;
081    
082        /**
083         * Indicates whether argument values must be present for the CommandLine to
084         * be valid.
085         *
086         * @see #getMinimum()
087         * @see #getMaximum()
088         * @return true iff the CommandLine will be invalid without at least one 
089         *         value
090         */
091        boolean isRequired();
092    
093        /**
094         * Retrieves the minimum number of values required for a valid Argument
095         *
096         * @return the minimum number of values
097         */
098        int getMinimum();
099    
100        /**
101         * Retrieves the maximum number of values acceptable for a valid Argument
102         *
103         * @return the maximum number of values
104         */
105        int getMaximum();
106    }